<h1>pyro:navigation</h1>

<p>The <em>navigation</em> tag creates lists of navigation links based on navigation groups defined in the Design -> Navigation section of PyroCMS.</p>

<h2>Tags</h2>

<h3>{pyro:navigation:links}</h3><br />

<p>Creates a list of links for a group.</p>

<p><strong>Parameters</strong></p>

<table cellpadding="0" cellspacing="0">

	<tr>
		<th>Parameter</th>
		<th>Default</th>
		<th>Description</th>
	</tr>
	
	<tr>
		<td width="100">group</td>
		<td width="100"></td>
		<td>Required. The navigation group the tag should use.</td>
	</tr>
	<tr>
		<td>list_tag</td>
		<td>ul</td>
		<td>Choose between ol and ul lists. The value of this is wrapped in brackets on either end.</td>
	</tr>
	<tr>
		<td>tag</td>
		<td>li</td>
		<td>Type of tag that surrounds each navigation item. The value of this is wrapped in brackets on either end.</td>
	</tr>
	<tr>
		<td>class</td>
		<td>current</td>
		<td>The class to use when an element is the current page.</td>
	</tr>
	<tr>
		<td>separator</td>
		<td>None</td>
		<td>String that separates each navigation item.</td>
	</tr>
	<tr>
		<td>items_only</td>
		<td>false</td>
		<td>true or false. Set if the output source code should be wrapped with an optional list_tag.</td>
	</tr>
	<tr>
		<td>indent</td>
		<td>None</td>
		<td>tab or space. Character used to indent the output of source code.</td>
	</tr>
	<tr>
		<td>link_class</td>
		<td>None</td>
		<td>The class names to apply in all anchor elements.</td>
	</tr>
	<tr>
		<td>top</td>
		<td>None</td>
		<td>Set to "text" and the top level menu items will be rendered as plain text instead of links.</td>
	</tr>

</table>

<p><strong>Examples</strong></p>

<h3>Simple Usage</h3>

<p>
	You can use the basic single-tag approach to output a chunk of HTML by itself. This will apply the class names to the <kdb>&lt;li&gt;</kdb>
	tags (default) and use the <kdb>&lt;a&gt;</kdb> tags (default) to wrap the anchors. 
</p>

<pre><code>{pyro:navigation:links group="header"}

Return:

&lt;li class="first current"&gt;&lt;a href="http://localhost/pyrocms/index.php">Home&lt;/a&gt;&lt;/li&gt;&lt;li class="last"&gt;&lt;a href="...
http://www.google.com"&gt;About Us&lt;/a&gt;&lt;/li&gt;</code></pre>

<p>
	You can use the basic single-tag approach like this to output a chunk of HTML that renders indented source code and adds a custom class name to all link anchors.
</p>

<pre><code>{pyro:navigation:links group="header" indent="tab" link_class="foo"}

Return:

&lt;li class="first current"&gt;
	&lt;a href="http://localhost/pyrocms/index.php" class="foo">Home&lt;/a&gt;
&lt;/li&gt;
&lt;li class="last"&gt;
	&lt;a href="http://www.google.com" class="foo"&gt;About Us&lt;/a&gt;
&lt;/li&gt;</code></pre>

<p>
	If you use nested links the default tag outputs the following html when menu items are arranged in a multilevel menu.
</p>

<pre><code>{pyro:navigation:links group="header" indent="tab"}

Return:
&lt;li class=&quot;first current&quot;&gt;
	&lt;a href=&quot;http://example.com/home&quot;&gt;Home&lt;/a&gt;
&lt;/li&gt;
&lt;li class=&quot;&quot;&gt;
	&lt;a href=&quot;http://example.com/about-us&quot;&gt;About Us&lt;/a&gt;
	&lt;ul&gt;
		&lt;li class=&quot;first&quot;&gt;
			&lt;a href=&quot;http://example.com/contact&quot;&gt;Contact&lt;/a&gt;
		&lt;/li&gt;
		&lt;li class=&quot;last&quot;&gt;
			&lt;a href=&quot;http://example.com/staff&quot;&gt;Staff&lt;/a&gt;
			&lt;ul&gt;
				&lt;li class=&quot;single&quot;&gt;
					&lt;a href=&quot;http://example.com/history&quot;&gt;History&lt;/a&gt;
				&lt;/li&gt;
			&lt;/ul&gt;
		&lt;/li&gt;
	&lt;/ul&gt;
&lt;/li&gt;
&lt;li class=&quot;last&quot;&gt;
	&lt;a href=&quot;http://example.com/blog&quot;&gt;Blog&lt;/a&gt;
&lt;/li&gt;
</code></pre>

<h3>Advanced Options</h3>

<p>
	You can use a combination of params to output a chunk of HTML that shows a short paragraph of navigation, using <kdb>&lt;p&gt;</kdb> as list_tag
	to wrap all items by disabling items_only and using the tag <kdb>&lt;span&gt;</kdb> to wrap each anchor link.
</p>

<pre><code>{pyro:navigation:links group="header" tag="span" class="active" separator="|" list_tag="p" items_only="false"}

Return:

&lt;p&gt;&lt;span class="first active"&gt;&lt;a href="http://localhost/pyrocms/index.php">Home&lt;/a&gt;&lt;/span&gt; | &lt;span class="last"&gt;...
&lt;ahref="http://www.google.com"&gt;About Us&lt;/a&gt;&lt;/span&gt;&lt;/p&gt;</code></pre>

<p>
	If this layout is not flexible enough you can use double-tags to control how each link is output yourself.
</p>

<pre><code>{pyro:navigation:links group="header"}
	&lt;li class="menu-item"&gt;&lt;a href="{url}" class="{class}"&gt;{title}&lt;/a&gt;&lt;/li&gt;
{/pyro:navigation:links}
</code></pre>